/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup HiDebug
 * @{
 *
 * @brief 提供调试代码的定义。
 *
 * 本模块函数可用于获取cpu uage、memory、heap、capture trace等。
 *
 * @since 12
 */

/**
 * @file hidebug_type.h
 *
 * @brief HiDebug模块代码结构体定义。
 * @kit PerformanceAnalysisKit
 * @include <hidebug/hidebug_type.h>
 * @library libohhidebug.so
 * @syscap SystemCapability.HiviewDFX.HiProfiler.HiDebug
 * @since 12
 */

#ifndef HIVIEWDFX_HIDEBUG_TYPE_H
#define HIVIEWDFX_HIDEBUG_TYPE_H

#include <stdint.h>
#include <stddef.h>
#include <unistd.h>
#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 错误码定义。
 *
 * @since 12
 */
typedef enum HiDebug_ErrorCode {
    /** 成功。 */
    HIDEBUG_SUCCESS = 0,
    /** 无效参数，可能的原因： 1.参数传值问题；2.参数类型问题。 */
    HIDEBUG_INVALID_ARGUMENT = 401,
    /** 重复采集。 */
    HIDEBUG_TRACE_CAPTURED_ALREADY = 11400102,
    /** 没有写文件的权限。 */
    HIDEBUG_NO_PERMISSION = 11400103,
    /** 系统内部错误。 */
    HIDEBUG_TRACE_ABNORMAL = 11400104,
    /** 当前没有trace正在运行。 */
    HIDEBUG_NO_TRACE_RUNNING = 11400105,
    /**
     * 传入符号解析函数的pc地址是无效的。
     * @since 20
     */
    HIDEBUG_INVALID_SYMBOLIC_PC_ADDRESS = 11400200,
    /**
     * @brief 当前设备不支持。
     * @since 22
     */
    HIDEBUG_NOT_SUPPORTED = 11400300,
    /**
     * @brief 当前进程正在采样。
     * @since 22
     */
    HIDEBUG_UNDER_SAMPLING = 11400301,
    /**
     * @brief 采样资源不可用。
     * @since 22
     */
    HIDEBUG_RESOURCE_UNAVAILABLE = 11400302,
} HiDebug_ErrorCode;

/**
 * @brief 应用程序所有线程的CPU使用率结构体定义。
 *
 * @since 12
 */
typedef struct HiDebug_ThreadCpuUsage {
    /**
     * 线程ID。
     */
    uint32_t threadId;
    /**
     * 线程CPU使用率百分比。
     */
    double cpuUsage;
    /**
     * 下一个线程的使用率信息。
     */
    struct HiDebug_ThreadCpuUsage *next;
} HiDebug_ThreadCpuUsage;

/**
 * @brief HiDebug_ThreadCpuUsage指针定义。
 *
 * @since 12
 */
typedef HiDebug_ThreadCpuUsage* HiDebug_ThreadCpuUsagePtr;

/**
 * @brief 系统内存信息结构类型定义。
 *
 * @since 12
 */
typedef struct HiDebug_SystemMemInfo {
    /**
     * 系统总的内存，以KB为单位。
     */
    uint32_t totalMem;
    /**
     * 系统空闲的内存，以KB为单位。
     */
    uint32_t freeMem;
    /**
     * 系统可用的内存，以KB为单位。
     */
    uint32_t availableMem;
} HiDebug_SystemMemInfo;

/**
 * @brief 应用程序进程本机内存信息结构类型定义。
 *
 * @since 12
 */
typedef struct HiDebug_NativeMemInfo {
    /**
     * 进程比例集大小内存，以KB为单位。
     */
    uint32_t pss;
    /**
     * 虚拟内存大小，以KB为单位。
     */
    uint32_t vss;
    /**
     * 常驻集大小，以KB为单位。
     */
    uint32_t rss;
    /**
     * 共享脏内存的大小，以KB为单位。
     */
    uint32_t sharedDirty;
    /**
     * 专用脏内存的大小，以KB为单位。
     */
    uint32_t privateDirty;
    /**
     * 共享干净内存的大小，以KB为单位。
     */
    uint32_t sharedClean;
    /**
     * 专用干净内存的大小，以KB为单位。
     */
    uint32_t privateClean;
} HiDebug_NativeMemInfo;

/**
 * @brief 应用程序进程内存限制结构类型定义。
 *
 * @since 12
 */
typedef struct HiDebug_MemoryLimit {
    /**
     * 应用程序进程驻留集的限制，以KB为单位。
     */
    uint64_t rssLimit;
    /**
     * 应用程序进程的虚拟内存限制，以KB为单位。
     */
    uint64_t vssLimit;
} HiDebug_MemoryLimit;

/**
 * @brief 采集trace线程的类型。
 *
 * @since 12
 */
typedef enum HiDebug_TraceFlag {
    /** 只采集当前应用主线程。 */
    HIDEBUG_TRACE_FLAG_MAIN_THREAD = 1,
    /** 采集当前应用下所有线程。 */
    HIDEBUG_TRACE_FLAG_ALL_THREADS = 2
} HiDebug_TraceFlag;

/**
 * @brief js栈帧内容的定义。
 *
 * @since 20
 */
typedef struct HiDebug_JsStackFrame {
    /**
     * 相对pc地址。当前pc相对于其所在的映射区域（如可执行文件或共享库）起始地址的偏移量。
     */
    uint64_t relativePc;

    /**
     * 代码所在的行号。当前栈帧对应的代码位于文件的具体行位置。
     */
    int32_t line;

    /**
     * 代码所在的列号。当前栈帧对应的代码在指定行的具体列位置。
     */
    int32_t column;

    /**
     * 映射名称。当前栈帧所属的映射区域的名称。
     */
    const char* mapName;

    /**
     * 函数名称。当前栈帧对应的函数的名称。
     */
    const char* functionName;

    /**
     * URL地址。当前栈帧对应代码的文件的URL，无论是本地文件路径还是远程服务器上的文件地址，通过该URL能找到对应的代码文件。
     */
    const char* url;

    /**
     * 包名。当前栈帧对应的代码所属包的名称。
     */
    const char* packageName;
} HiDebug_JsStackFrame;

/**
 * @brief native栈帧内容的定义。
 *
 * @since 20
 */
typedef struct HiDebug_NativeStackFrame {
    /**
     * 相对pc地址。当前pc相对于其所在的映射区域（如可执行文件或共享库）起始地址的偏移量。
     */
    uint64_t relativePc;

    /**
     * 函数偏移量。当前栈帧对应的函数在其所在的映射区域（如可执行文件或共享库）内的偏移量。
     */
    uint64_t funcOffset;

    /**
     * 映射名称。当前栈帧所属的映射区域的名称。
     */
    const char* mapName;

    /**
     * 函数名称。当前栈帧对应的函数的名称。
     */
    const char* functionName;

    /**
     * 构建标识符。当前映射区域（如可执行文件或共享库）相关的唯一标识符。在调试和符号解析时，buildId可确保使用的符号文件与实际运行的二进制文件版本一致。
     */
    const char* buildId;

    /**
     * 保留字段。为了后续扩展预留的字段。
     */
    const char* reserved;
} HiDebug_NativeStackFrame;

/**
 * @brief 栈帧类型的枚举值定义。
 *
 * @since 20
 */
typedef enum HiDebug_StackFrameType {
    /** js类型栈帧。*/
    HIDEBUG_STACK_FRAME_TYPE_JS = 1,
    /** native类型栈帧。 */
    HIDEBUG_STACK_FRAME_TYPE_NATIVE = 2,
} HiDebug_StackFrameType;

/**
 * @brief 栈帧内容的定义。
 *
 * @since 20
 */
typedef struct HiDebug_StackFrame {
    /**
     * 当前栈的类型。
     */
    HiDebug_StackFrameType type;

    /** 栈帧内容。 */
    union {
        /** 由{@link HiDebug_JsStackFrame}定义的js栈帧内容。 */
        struct HiDebug_JsStackFrame js;
        /** 由{@link HiDebug_NativeStackFrame}定义的native栈帧内容。 */
        struct HiDebug_NativeStackFrame native;
    } frame;
} HiDebug_StackFrame;

/**
 * @brief 用于栈回溯及栈解析的对象。
 *
 * @since 20
 */
typedef struct HiDebug_Backtrace_Object__* HiDebug_Backtrace_Object;

/**
 * @brief 应用程序进程可替换/恢复的HiDebug_MallocDispatch表结构类型定义。
 *
 * @since 20
*/
typedef struct HiDebug_MallocDispatch {
    /**
     * 开发者自定义malloc函数指针。
     */
    void* (*malloc)(size_t);
    /**
     * 开发者自定义calloc函数指针。
     */
    void* (*calloc)(size_t, size_t);
    /**
     * 开发者自定义realloc函数指针。
     */
    void* (*realloc)(void*, size_t);
    /**
     * 开发者自定义free函数指针。
     */
    void (*free)(void*);
    /**
     * 开发者自定义mmap函数指针。
     */
    void* (*mmap) (void*, size_t, int, int, int, off_t);
    /**
     * 开发者自定义munmap函数指针。
     */
    int (*munmap) (void*, size_t);
} HiDebug_MallocDispatch;

/**
* @brief 应用图形显存占用详情的结构定义。
*
* @since 21
*/
typedef struct HiDebug_GraphicsMemorySummary {
   /**
    * @brief gl内存大小，进程统计的DMA内存占用，包括直接通过接口申请的DMA buffer和通过allocator_host申请的DMA buffer，以KB为单位。
    */
    uint32_t gl;

   /**
    * @brief graph内存大小，RenderService渲染进程加载所需资源占用的内存，例如图片、纹理等，以KB为单位。
    */
    uint32_t graph;
} HiDebug_GraphicsMemorySummary;

/**
 * @brief 采样配置的结构定义
 *
 * @since 22
 */
typedef struct HiDebug_ProcessSamplerConfig {
    /**
     * 待采样的线程号数组。最大支持10个线程的同时采样，数组长度超出时，将取前10个线程进行采样。
     */
    uint32_t* tids;

    /**
     * tids指向的数组长度。
     */
    uint32_t size;

    /**
     * 采样频率，取值范围[1-1000]，单位HZ。超出取值范围时取默认值100。
     */
    uint32_t frequency;

    /**
     * 采样时长，取值范围[1000-10000]，单位ms。小于1000时，接口调用异常；大于10000时，取10000。
     */
    uint32_t duration;

    /**
     * 保留字段。
     */
    uint32_t reserved;
} HiDebug_ProcessSamplerConfig;

#ifdef __cplusplus
}
#endif

/**
 * @brief FFRT任务标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_FFRT (1ULL << 13)
/**
 * @brief 公共库子系统标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_COMMON_LIBRARY (1ULL << 16)
/**
 * @brief HDF子系统标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_HDF (1ULL << 18)
/**
 * @brief 网络标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_NET (1ULL << 23)
/**
 * @brief NWeb标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_NWEB (1ULL << 24)
/**
 * @brief 分布式音频标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_AUDIO (1ULL << 27)
/**
 * @brief 文件管理标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_FILE_MANAGEMENT (1ULL << 29)
/**
 * @brief OHOS通用标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_OHOS (1ULL << 30)
/**
 * @brief Ability Manager标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_ABILITY_MANAGER (1ULL << 31)
/**
 * @brief 相机模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_CAMERA (1ULL << 32)
/**
 * @brief 媒体模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_MEDIA (1ULL << 33)
/**
 * @brief 图像模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_IMAGE (1ULL << 34)
/**
 * @brief 音频模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_AUDIO (1ULL << 35)
/**
 * @brief 分布式数据管理器模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_DATA (1ULL << 36)
/**
 * @brief 图形模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_GRAPHICS (1ULL << 38)
/**
 * @brief ArkUI开发框架标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_ARKUI (1ULL << 39)
/**
 * @brief 通知模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_NOTIFICATION (1ULL << 40)
/**
 * @brief MISC模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_MISC (1ULL << 41)
/**
 * @brief 多模态输入模块标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_MULTIMODAL_INPUT (1ULL << 42)
/**
 * @brief RPC标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_RPC (1ULL << 46)
/**
 * @brief JSVM虚拟机标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_ARK (1ULL << 47)
/**
 * @brief 窗口管理器标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_WINDOW_MANAGER (1ULL << 48)
/**
 * @brief 分布式屏幕标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_SCREEN (1ULL << 50)
/**
 * @brief 分布式相机标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_CAMERA (1ULL << 51)
/**
 * @brief 分布式硬件框架标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_HARDWARE_FRAMEWORK (1ULL << 52)
/**
 * @brief 全局资源管理器标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_GLOBAL_RESOURCE_MANAGER (1ULL << 53)
/**
 * @brief 分布式硬件设备管理器标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_HARDWARE_DEVICE_MANAGER (1ULL << 54)
/**
 * @brief SA标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_SAMGR (1ULL << 55)
/**
 * @brief 电源管理器标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_POWER_MANAGER (1ULL << 56)
/**
 * @brief 分布式调度程序标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_SCHEDULER (1ULL << 57)
/**
 * @brief 分布式输入标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_DISTRIBUTED_INPUT (1ULL << 59)
/**
 * @brief 蓝牙标签。
 *
 * @since 12
 */
#define HIDEBUG_TRACE_TAG_BLUETOOTH (1ULL << 60)

/** @} */

#endif // HIVIEWDFX_HIDEBUG_TYPE_H